<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<!-- saved from url=(0014)about:internet -->
<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>
	Using AspDriver
</title>

<link rel="stylesheet" href="_CodeDoc.css" />

<style type="text/css">
.Reference
{
	color: #003399;
}
</style>

</head>

<body id="DocBrowserTopic">

<div class="TopicHeader">
	<div class="Supertitle_">
		HomeUX Driver Collection
	</div>
	Using AspDriver
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="Summary">

<p>This page documents how to use <b>AspDriver</b> (in AspDriver.dll), the HomeUX-compatible driver
that controls one or more Sound Control Technologies ASP Audio Matrix 8x8 devices connected
together to implement an N-input, N-output audio router.  <b>AspSimulator</b> (in AspSimulator.dll)
is also documented here.</p>

<p>Page contents:</p>
<ul>
	<li><a href="#Overview">Hardware &amp; Driver Overview</a></li>
	<li><a href="#Config">Configuring AspDriver</a></li>
	<li><a href="#Use">Using AspDriver</a></li>
	<li><a href="#Sim">AspSimulator</a></li>
</ul>

</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Hardware &amp; Driver Overview<a name="Overview"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>A <a href="http://www.soundcontrol.net/">Sound Control Technologies</a> ASP Audio Matrix 8x8
	device&mdash;abbreviated "ASP" in this documentation&mdash;is an audio mixing device that has
	8 audio inputs and 8 audio outputs.  Any input can be routed to any output, and inputs can be
	mixed with the result directed to an output.  Multiple ASP units can be connected together to
	form a 16x16 mixer array, 24x24 mixer array, etc.</p>

	<p>AspDriver allows a HomeUX installation to control a subset of the functionality of an
	ASP mixer or mixer array:</p>
	<ul>

		<li>Inputs and outputs are assigned names.</li>

		<li>At most two inputs can be connected to a given output.  Therefore, AspDriver
			reduces the functionality of the ASP hardware from a "mixer" to something that's more
			like a "router".
			<ul>
		
				<li>Effectively, AspDriver routes
					<a href="http://en.wikipedia.org/wiki/Monaural">mono</a> audio signals.
					AspDriver can be used with AggregatorDriver to simplify routing of stereo
					signals.</li>

				<li>The purpose of allowing two inputs per output is for the situation where a
					stereo signal needs to be converted to a mono output.</li>

			</ul></li>

		<li>The volume and mute setting of each output can be controlled.</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Configuring AspDriver<a name="Config"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>AspDriver is configured in the HomeUX configuration file.  Here's the general
	structure (simplified):</p>

	<table class="Grid Code">
		<col class="Column1_" />
		<tr class="Header_">
			<td class="Header1_">XML</td>
		</tr>
		<tr>
			<td class="Content_ Indent_">
				&lt;configuration&gt;
					<div>&lt;HomeUXSettings&gt;
						<div><a href="#Device">&lt;Device Driver="AspDriver.dll"&gt;</a>
							<div><a href="#Input">&lt;Input/&gt;</a>*</div>
							<div><a href="#Output">&lt;Output/&gt;</a>*</div>
						</div>
						<div>&lt;/Device&gt;</div>
					</div>
					<div>&lt;/HomeUXSettings&gt;</div>
				&lt;/configuration&gt;
			</td>
		</tr>
	</table>

	<p>"<tt>*</tt>" means "zero or more allowed".  Children of <tt>&lt;Device
	Driver="AspDriver.dll"&gt;</tt> can appear in any order.</p>

	<p>Example:</p>

	<table class="Grid Code">
		<col class="Column1_" />
		<tr class="Header_">
			<td class="Header1_">XML</td>
		</tr>
		<tr>
			<td class="Content_">
	<pre>
&lt;configuration&gt;
  ...
  &lt;HomeUXSettings&gt;
    ...

    &lt;Device Name="ASP" Driver="AspDriver.dll" Units="3"
          sim:SerialPort="AspSimulator.dll;;Units=3;Test=0"
          real:SerialPort="COM7,38400,8,n,1,RtsEnable,DtrEnable"&gt;

      &lt;Input Name="DVD/CD L"                InputId="7" /&gt;
      &lt;Input Name="DVD/CD R"                InputId="8" /&gt;
      &lt;Input Name="Music Server L"          InputId="17" /&gt;
      &lt;Input Name="Music Server R"          InputId="18" /&gt;
      &lt;Input Name="Music Server Rear L"     InputId="15" /&gt;
      &lt;Input Name="Music Server Rear R"     InputId="16" /&gt;
      &lt;Input Name="DVR L"                   InputId="5" /&gt;
      &lt;Input Name="DVR R"                   InputId="6" /&gt;
      &lt;Input Name="VCR L"                   InputId="11" /&gt;
      &lt;Input Name="VCR R"                   InputId="12" /&gt;

      &lt;Output Name="Exercise E + Bathroom"  OutputId="4" /&gt; &lt;!-- Right --&gt;
      &lt;Output Name="Exercise W + Shower"    OutputId="3" /&gt; &lt;!-- Left --&gt;
      &lt;Output Name="Game Room NE"           OutputId="7" /&gt;
      &lt;Output Name="Game Room NW"           OutputId="8" /&gt;
      &lt;Output Name="Game Room SE"           OutputId="11" /&gt;
      &lt;Output Name="Game Room SW"           OutputId="12" /&gt;
      &lt;Output Name="Game Room TV L"         OutputId="15" /&gt;
      &lt;Output Name="Game Room TV R"         OutputId="16" /&gt;
      &lt;Output Name="Kitchen E"              OutputId="1" /&gt; &lt;!--Left--&gt;
      &lt;Output Name="Kitchen W"              OutputId="2" /&gt; &lt;!-- Right --&gt;
      &lt;Output Name="Laundry Room"           OutputId="9" /&gt; &lt;!-- Mono --&gt;
      &lt;Output Name="Master Bedroom TV L"    OutputId="13" /&gt;
      &lt;Output Name="Master Bedroom TV R"    OutputId="14" /&gt;
      &lt;Output Name="Office N"               OutputId="6" /&gt; &lt;!--Left--&gt;
      &lt;Output Name="Office S"               OutputId="5" /&gt; &lt;!--Right--&gt;
      &lt;Output Name="Patio N"                OutputId="21" /&gt; &lt;!-- Left --&gt;
      &lt;Output Name="Patio S"                OutputId="22" /&gt; &lt;!-- Right --&gt;
      &lt;Output Name="Deck N"                 OutputId="19" /&gt; &lt;!-- Left --&gt;
      &lt;Output Name="Deck S"                 OutputId="20" /&gt; &lt;!-- Right --&gt;
      &lt;Output Name="Sunfire L"              OutputId="17" /&gt;
      &lt;Output Name="Sunfire R"              OutputId="18" /&gt;

    &lt;/Device&gt;

  ...
  &lt;/HomeUXSettings&gt;
&lt;/configuration&gt;
	</pre>
			</td>
		</tr>
	</table>

	<p>The following subsections describe the AspDriver configuration file XML elements.</p>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Device Driver="AspDriver.dll"&gt;<a name="Device"></a>
	</div>
	<div class="Section">

		<p>(Required, used within <tt>&lt;HomeUXSettings&gt;</tt>.) Specifies an instance of
		AspDriver, which is used to control an ASP mixer array.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Device
						<div>Name="..."</div>
						<div>Driver="AspDriver.dll"</div>
						<div>Units="..."</div>
						<div>SerialPort="..."&gt;</div>
						<div><a href="#Input">&lt;Input/&gt;</a>*</div>
						<div><a href="#Output">&lt;Output/&gt;</a>*</div>
					&lt;/Device&gt;
				</td>
			</tr>
		</table>

		<p>"<tt>*</tt>" means "zero or more allowed".</p>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the device.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Driver</p>
			<p class="AttributeDescription">(String, required.)
				Must be "<tt>AspDriver.dll</tt>".
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Units</p>
			<p class="AttributeDescription">(Integer, required.)
				The number of ASP Audio Matrix 8x8 devices connected together.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">SerialPort</p>
			<p class="AttributeDescription">(String, required.)
				A standard HomeUX serial port specification.  Identifies the serial port (real or
				virtual) that the hardware is connected to.  When connected to a real serial port,
				the parameters should be "<i>port-name</i>,38400,8,n,1,RtsEnable,DtrEnable" in
				order to correctly operate an ASP unit.
			</p>
			</div>

		</div>

	</div>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Input&gt;<a name="Input"></a>
	</div>
	<div class="Section">

		<p>(Zero or more, used within <a href="#Device">&lt;Device Driver="AspDriver.dll"&gt;</a>.)
		Specifies one input on the ASP mixer array.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Input
						<div>Name="..."</div>
						<div>InputId="..."</div>
					/&gt;
				</td>
			</tr>
		</table>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the input.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">InputId</p>
			<p class="AttributeDescription">(Integer, required.)
				The input number.  For the first (or only) ASP 8x8 unit, this is a number from 1 to
				8, inclusive; for the second unit, it's from 9 to 16, inclusive; and so on.
			</p>
			</div>

		</div>

	</div>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Output&gt;<a name="Output"></a>
	</div>
	<div class="Section">

		<p>(Zero or more, used within <a href="#Device">&lt;Device Driver="AspDriver.dll"&gt;</a>.)
		Specifies one output on the ASP mixer array.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Output
						<div>Name="..."</div>
						<div>OutputId="..."</div>
					/&gt;
				</td>
			</tr>
		</table>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the output.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">OutputId</p>
			<p class="AttributeDescription">(Integer, required.)
				The output number.  For the first (or only) ASP 8x8 unit, this is a number from 1
				to 8, inclusive; for the second unit, it's from 9 to 16, inclusive; and so on.
			</p>
			</div>

		</div>

	</div>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Using AspDriver<a name="Use"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>AspDriver implements the following SyncPath schema:</p>
	<ul>

		<li><b><tt><i>device-name</i>\Outputs\<i>output-name</i>\Volume</tt></b><br/>
			Gets or sets the volume of output <i>output-name</i> of device <i>device-name</i>,
			between 0.0 and 1.0, inclusive.  1.0 corresponds to maximum volume; each 0.03
			decrease in the volume level corresponds to a 1-decibel reduction.</li>

		<li><b><tt><i>device-name</i>\Outputs\<i>output-name</i>\IsMuted</tt></b><br/>
			Gets or sets the mute setting of output <i>output-name</i> of device
			<i>device-name</i>, (<tt>true</tt> or <tt>false</tt>).</li>

		<li><b><tt><i>device-name</i>\Outputs\<i>output-name</i>\Input</tt></b><br/>
			Gets or sets the name of the first input connected to the output <i>output-name</i> of
			device <i>device-name</i>, or "<tt>-</tt>" if the first input is unconnected.
			</li>

		<li><b><tt><i>device-name</i>\Outputs\<i>output-name</i>\Input 2</tt></b><br/>
			Gets or sets the name of the second input connected to the output <i>output-name</i> of
			device <i>device-name</i>, or "<tt>-</tt>" if the second input is unconnected.</li>

		<li><b><tt>Configuration\<i>device-name</i>\InputNames\<i>input-name</i></tt></b><br/>
			Gets the display label for input <i>input-name</i> of device <i>device-name</i>;
			currently the display label is the same as <i>input-name</i>.  This can be used to
			enumerate inputs.  There's also a special value,
			<tt>Configuration\<i>device-name</i>\InputNames\-</tt> (the last segment is a hyphen
			"<tt>-</tt>") which is used to indicate an unconnected input.</li>

		<li><b><tt>Configuration\<i>device-name</i>\OutputNames\<i>output-name</i></tt></b><br/>
			Gets the display label for output <i>output-name</i> of device <i>device-name</i>;
			currently the display label is the same as <i>output-name</i>.  This can be used to
			enumerate outputs.</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	AspSimulator<a name="Sim"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p><b>AspSimulator</b> is a HomeUX-compatible virtual serial port implementation that simulates
	a subset of the serial communication behavior ASP hardware.  AspSimulator performs no
	real-world actions&mdash;the simulation is purely for the purposes of testing a HomeUX
	installation without having to connect to real hardware.</p>

	<p>To use AspSimulator in HomeUX, set the SerialPort attribute of the
	<a href="#Device">&lt;Device Driver="AspDriver.dll"&gt;</a> configuration element to a string
	with the following format:</p>

	<code class="Indent">
          AspSimulator.dll;;Units=<i>unit-count</i>;Test=<i>test-number</i>
	</code>

	<p>Parameters:</p>
	<ul>

		<li><p><i>unit-count</i> is the number of simulated ASP Audio Matrix 8x8 devices connected
			together; it should be the same number as the "Units" attribute of the
			<a href="#Device">&lt;Device Driver="AspDriver.dll"&gt;</a> configuration element.  The
			default is 1.</p></li>

		<li><p><i>test-number</i> specifies test behavior.  This is for development use only; use 0
			to specify normal behavior.  The default is 0.</p></li>

	</ul>

	<p>You can test AspSimulator independently of HomeUX, using the VSerial console
	application:</p>

	<code class="Indent">
          VSerial.exe -cr -dll AspSimulator.dll;;Units=<i>unit-count</i>;Test=<i>test-number</i>
	</code>

	<p>AspSimulator implements a limited simulation&mdash;only the following hardware commands are
	currently supported.  (See ASP hardware documentation for information about hardware commands
	and notifications.)</p>
	<ul>

 		<li><p>"INGAIN" and "ALLINGAIN": Set mode only, not request mode.  Syntax:</p>
			<ul>
				<li><tt>INGAIN=<i>input</i>,<i>gain</i></tt></li>
				<li><tt>ALLINGAIN=<i>gain</i>,<i>gain</i>,...</tt></li>
			</ul>
			<p><i>input</i> is an input channel number (1 to N); <i>gain</i> is "L0" (0 dB), "L1"
			(+10 dB), "H0" (+50 dB), "H1" (+60 dB).</p></li>

 		<li><p>"GAIN" and "ALLGAIN": Both set and request mode.  Gain value can be a decimal value
			0-70 or "M"; "+" and "-" are not supported.  "ALLGAIN" supports only full array mode,
			not sparse array etc.  Note that real ASP units are limited to 1-dB steps for gain
			values.  Syntax:</p>
			<ul>
				<li><tt>GAIN=<i>input</i>,<i>output</i></tt> (request)</li>
				<li><tt>GAIN=<i>input</i>,<i>output</i>,<i>gain</i></tt> (set)</li>
				<li><tt>ALLGAIN=<i>input</i></tt> (request)</li>
				<li><tt>ALLGAIN=<i>input</i>,<i>gain</i>,<i>gain</i>,...</tt>(set)</li>
			</ul>
			<p><i>input</i> is an input channel number (1 to N); <i>output</i> is an output channel
			number (1 to N); <i>gain</i> is a dB dB value (0-70) or "M" (mute).</p></li>

 		<li><p>"MASTER": Both set and request mode.  Gain value can be a decimal value 0-31.  Note
			that some actual ASP units (such as version 0.98) support 1-dB steps, but according to
			the documentation at least some unit support 1.5-dB steps.  Syntax:</p>
			<ul>
				<li><tt>MASTER=<i>output</i></tt> (request mode)</li>
				<li><tt>MASTER=<i>output</i>,<i>gain</i></tt> (set mode)</li>
			</ul>
			<p><i>output</i> is an output channel number (1 to N); <i>gain</i> is a dB value (0-31)
			or "M" (mute).</p></li>

 		<li><p>"RESTORE": Only preset 1 supported.  That preset cannot be altered: it does the same
			as restarting the simulator.  All channels and crosspoints are muted.  Syntax:</p>
			<ul>
				<li><tt>RESTORE=1</tt></li>
			</ul>
			</li>

 		<li><p>"STATUS2": Only "ALLGAIN" and "ALLMASTER" lines are output.  Syntax:</p>
			<ul>
				<li><tt>STATUS2</tt></li>
			</ul>
			</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="TopicFooter">
</div>

<div class="PageFooter">
<p>See <a href="http://www.HomeUX.org">http://www.HomeUX.org</a> for more information about HomeUX.</p>
</div>

</body>

</html>

